home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 311_01 / db.doc < prev    next >
Text File  |  1990-04-21  |  48KB  |  1,459 lines
  1.  
  2.  
  3.                          
  4.  
  5.  
  6.  
  7.  
  8.         ######    ######        ######    #######  #####
  9.         #     # #     #     #     # #     # #     #
  10.         #     # #     #     #     # #     # #
  11.         #     # ######        #     # #     # #
  12.         #     # #     #   ###    #     # #     # #
  13.         #     # #     #   ###    #     # #     # #     #
  14.         ######    ######      ###    ######    #######  #####
  15.             
  16.  
  17.             #     #    #         #####
  18.             #     #   ##        #     #
  19.             #     #  # #              #
  20.             #     #    #         #####
  21.              #   #       #      ###          #
  22.               # #       #      ###    #     #
  23.                #     #####      ###     #####
  24.  
  25.  
  26.  
  27.               (c) 1987, 1990
  28.  
  29.                               Ken Harris
  30.                   901 E. Hampton
  31.                   Milwaukee, WI  53217
  32.                   (414) 962-1961
  33.                   harris@cvax.cs.uwm.edu
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50. /****************************************************************************/
  51. /*                                                                          */
  52. /*      This software is made available on an AS-IS basis. Unrestricted     */
  53. /*      use is granted provided that the copyright notice remains intact.   */
  54. /*    The author makes no warranties expressed or implied; however, any   */
  55. /*    feedback is welcome.                            */
  56. /*                                                                          */
  57. /****************************************************************************/
  58.          
  59.  
  60.     V1.2 Release Notes:
  61.     ---- ------- -----
  62.  
  63.     (1)  The DB_READ_LAST and DB_READ_PREV routines have been added
  64.          to allow backwards traversal. The routines work for all three
  65.          file types. DB_DELETE should not be used with these routines.
  66.          The delete routine sets the current record pointer so that a
  67.          subsequent DB_READ_NEXT will work correctly. A DB_READ_PREV
  68.          loop with DB_DELETES will result in skipped records.
  69.                                   
  70.  
  71.     (2)  A number of bugs in the file create routine have been fixed.
  72.  
  73.  
  74.     (3)  A file corruption bug in the Index delete routine has been
  75.          fixed.
  76.  
  77.  
  78.     (4)  The distribution has been divided into three separately
  79.          compiled files. 
  80.  
  81.  
  82.     (5)  Large memory model now works correctly.
  83.  
  84.  
  85.     (6)  A lot of "warning" type problems have been cleaned up.
  86.  
  87.     (7)  Just before releasing V1.2 Microsoft C V5.0 rolled in
  88.          the door so I was able to fix a couple of problems. 
  89.          There are still some warning messages while compiling
  90.          db_main.c. This is the result of ",..." type declarations
  91.          used to prevent type checking of the user_data argument.
  92.          User programs don't have to type cast user_data to char*
  93.          to avoid warnings.
  94.  
  95.     (8)  I have avoided the temptation of using too many of the
  96.          ANSI C extensions for those folks with old compilers.
  97.          Also I'd rather not fill the code with a zillion IFDEF's.
  98.          
  99.  
  100.  
  101.     V1.3 Release Notes:
  102.     ---- ------- -----
  103.  
  104.     (1)  A variable type file has been added. It is a sequential file
  105.          with variable length records.
  106.  
  107.     (2)  A simple object dictionary manager has been added. It works
  108.          well for a small data base of non-homogeneous objects, for
  109.          example setup data records.
  110.  
  111.     (3)  The file descriptor pointer is now called DATA_FILE instead of
  112.          DATA_SET. DATA_SET is still defined so that V1.2 programs
  113.          will compile.
  114.  
  115.     (4)  The db_create routine arguments have changed. An option
  116.          string is now passed instead of a df_file_hdr pointer. This
  117.          is much cleaner. It will require changing any V1.2 programs
  118.          before they will work.
  119.  
  120.     (5)  A number of routines now take an optional final record size
  121.          argument. This is only required for VAR type files. It may
  122.          be ignored for other file types.
  123.  
  124.     (6)  Existing V1.2 data files should work with V1.3 routines.
  125.          The first time the file is openned and updated the file
  126.          version will be changed from 1.2 to 1.3.
  127.  
  128.     (7)  Compiler conditionals have been added to DB_MAIN.C to
  129.          bracket references to file-type specific routines. This
  130.          makes it possible to build a library with support for
  131.          only file types you need. The lexical variables are
  132.          SEQ, RAN, IDX, VAR and ALL. So if SEQ is defined, then
  133.          sequential file support is included, etc. Note that
  134.          DB_DICT uses VAR files. If an attempt is made to access
  135.          an unsupported file-type an error will occur. 
  136.  
  137.          Only the references to routines are IFDEFed. If you build
  138.          a subset library you will probably get warning messages
  139.          about some unreferenced variables. It's ok.
  140.  
  141.     (8)  Compiler conditionals are used to bracket compiler specific
  142.          code. The current conditionals are:
  143.         MSC   - Microsoft C
  144.         TURBO - Turbo C
  145.         SYSV  - Unix Sys V 
  146.  
  147.          In addition ANSI can be defined to use ANSI style function
  148.          prototypes. You will probably want to edit #defines for
  149.          your compiler and ANSI at the beginning of db.h.
  150.  
  151.     (9)  A header file, dblib.h, has been added for building the
  152.          library. It is not needed for application programs. It
  153.          contains compiler specific includes and defines.
  154.  
  155.     V1.3 Release Notes (cont):
  156.     ---- ------- -----
  157.  
  158.     (10) The header file contains references to DB_LINK routines.
  159.          These are routines for linking records between files.
  160.          They have not been included in the distribution.
  161.  
  162.     (11) The routines memedt and stredt are no longer used by the
  163.          db routines and have been removed from the distribution.
  164.  
  165.     (12) The *test.c files are intended to provide a minimal test
  166.          of the routines. If the the tests run to compeletion
  167.          without crashing or generating a DB-ERROR then there is
  168.          a good chance that you're in business. The tests are
  169.          not necessarily good examples of using the routines.
  170.  
  171.     (13) The routines have been built and tested on several
  172.          different machines. Most of the development for v1.3
  173.          was done under Ultrix on a VAXstation-2000 with gcc.
  174.          It has also been sucessfully built using MSC 5.1 and
  175.          Turbo C 2.0 under MSDOS and cc under Unix on a 3B1. 
  176.  
  177.          If your compiler is not one of these you should still 
  178.          be able to build the routines without too much trouble.
  179.          Search through the code for MSC 's and add an
  180.          appropriate case for your compiler. 
  181.  
  182.     (14) Note that although this code works fine on Unix systems,
  183.          it is still single user. There is no support for record
  184.          locking or file sharing. 
  185.  
  186.         +----------+            -------------------               +----------+
  187.         | db_Intro |            - DB Introduction -               | db_Intro |
  188.         +----------+            -------------------               +----------+
  189.  
  190.  
  191.  
  192.         o Description
  193.  
  194.                     This document describes the DB package for maintaining
  195.             data files. The package consists of a library of file handling
  196.             routines which may be linked with user programs.
  197.  
  198.             The following four file organizations are supported:
  199.  
  200.                (1) Sequential - This file is a sequential stream of fixed
  201.                 length records.
  202.  
  203.                (2) Index      - Data records are stored in an ISAM type
  204.                                 organization.
  205.  
  206.                (3) Random     - Data records are stored using a hashed method.
  207.  
  208.            (4) Variable   - A sequential stream of variable length
  209.                 records.
  210.                      
  211.  
  212.             The following operations are supported:
  213.  
  214.             db_read_last         -  Read Last Record 
  215.             db_read_prev         -  Read Prev Record
  216.                 db_add               -  Add a New Record a File 
  217.                 db_close             -  Close an Open Data Set
  218.                 db_create            -  Create a New Data Set
  219.                 db_delete            -  Delete the Current Record
  220.                 db_dict_add          -  Dict Add Object
  221.                 db_dict_close        -  Dict Close 
  222.                 db_dict_delete       -  Dict Object Delete 
  223.                 db_dict_delete_all   -  Dict Delete A